BLUEPRINT
5 Schema와 산출물 관계
제5장: Schema와 산출물 관계
본 장에서는 CAP 프로젝트의 산출물 체계 구조를 기술하고, 프로토콜 Schema 정의 파일이 산출물에서 차지하는 핵심적 위치와 Schema 버전과 프로토콜 버전의 대응 관계를 명확히 한다. 산출물 간의 계층 관계와 의존 관계를 이해하는 것은 프로토콜 구현자와 커뮤니티 기여자가 프로젝트 협업에 참여하기 위한 기반이다.
5.1 세 가지 핵심 산출물
CAP 프로젝트의 산출물 체계는 세 가지 핵심 산출물로 구성되며, 문서에서 정의, 구현에 이르는 완전한 산출 체인을 형성한다:
| 산출물 범주 | 설명 | 저장소 경로 예시 |
|---|---|---|
| 다국어 프로토콜 문서 | 아키텍처 블루프린트(Blueprint)와 프로토콜 기술 규격(Specification)을 포함하며, 9개 언어로 등가 발행되어 프로토콜의 설계 의도, 능력 범위 및 기술 세부사항에 대한 인간 가독 기술을 제공한다 | docs/{lang}/blueprint/, docs/{lang}/specification/ |
| 프로토콜 Schema 정의 파일 | 프로토콜 메시지 형식의 권위적 정의로, 기계 가독 및 인간 가독의 다양한 형식으로 제공되며, SDK 구현과 상호운용성 테스트의 기준이다 | schema/{version}/ |
| 각 언어 SDK 구현 | 프로토콜의 구체적 프로그래밍 언어 구현으로, Schema 정의 파일을 기반으로 개발되며, 서로 다른 기술 스택의 개발자에게 즉시 사용 가능한 프로토콜 통합 기능을 제공한다 | sdk/{language}/ |
세 가지 산출물 간의 계층 관계:
- 다국어 프로토콜 문서는 전략 계층과 규격 계층에 위치하며, 프로토콜이 "무엇을 하는지"와 "어떻게 하는지"의 상위 설계를 정의한다
- 프로토콜 Schema 정의 파일은 정의 계층에 위치하며, 프로토콜 규격의 메시지 형식을 정밀하고 기계 처리 가능한 형식화된 정의로 변환한다
- 각 언어 SDK 구현은 구현 계층에 위치하며, Schema 정의 파일을 기반으로 프로토콜 능력을 직접 호출 가능한 프로그래밍 인터페이스로 변환한다
세 가지 산출물의 업데이트는 상위에서 하위로의 전달 경로를 따른다: 프로토콜 문서의 변경이 Schema 정의의 업데이트를 구동하고, Schema 정의의 업데이트가 SDK 구현의 적응을 구동한다.
5.2 Schema 정의 파일의 역할
Schema 정의 파일은 CAP 프로토콜 메시지 형식의 **권위적 정의(Authoritative Definition)**로, 프로젝트 산출물 체계에서 다음 핵심 역할을 담당한다:
- 메시지 형식의 유일한 진실 원천(Single Source of Truth): Schema 정의 파일은 CAP 프로토콜의 모든 메시지 유형의 필드 이름, 데이터 유형, 필수/선택 제약 및 중첩 구조를 정밀하게 기술한다. 프로토콜 문서의 텍스트 기술과 Schema 정의 간에 모호함이 존재할 때, Schema 정의를 기준으로 한다
- SDK 구현의 개발 기준: 각 언어 SDK의 메시지 직렬화/역직렬화 로직은 Schema 정의를 엄격히 따라야 한다. SDK 개발자는 Schema 정의 파일을 통해 각 메시지의 정밀한 구조를 파악하여 서로 다른 언어의 SDK 구현이 메시지 형식에서 완전히 일치하도록 보장한다
- 상호운용성 테스트의 검증 기준: 서로 다른 언어 SDK 간의 상호운용성 테스트는 Schema 정의를 검증 기준으로 한다. 한 SDK가 직렬화한 메시지는 다른 SDK가 올바르게 역직렬화할 수 있어야 하며, Schema 정의 파일이 "올바름"을 판정하는 유일한 근거이다
- 자동화 검증의 기반: Schema 정의 파일(특히 schema.json)은 자동화 도구가 직접 소비할 수 있으며, 메시지 형식의 자동 검증, 코드 생성 및 문서 생성에 사용되어 수동 오류를 줄인다
5.3 Schema 버전과 프로토콜 버전 대응 관계
정식 릴리스된 각 CAP 프로토콜 버전은 하나의 Schema 버전에 대응하며, Schema 파일은 프로토콜 버전 릴리스 날짜로 명명된 디렉토리에 저장되어 버전 대응 관계가 명확하고 추적 가능하도록 보장한다.
디렉토리 명명 규칙:
| 프로토콜 상태 | Schema 디렉토리 | 설명 |
|---|---|---|
| 초안(Draft) | schema/draft/ | 개발 중인 Schema 정의로, 언제든지 변경 가능하며 호환성을 보장하지 않는다 |
| 정식 릴리스 | schema/{YYYY-MM-DD}/ | 릴리스 날짜로 명명하며, 예: schema/2025-10-25/, 릴리스 후 변경 불가(immutable) |
버전 대응 규칙:
- 일대일 대응: 정식 릴리스된 각 프로토콜 버전은 정확히 하나의 Schema 버전 디렉토리에 대응하며, 디렉토리 이름은 해당 프로토콜 버전의 릴리스 날짜를 사용한다
- 초안 공유: 초안 단계의 모든 Schema 변경은
schema/draft/디렉토리를 공유하며, 초안 단계에서는 버전 번호를 구분하지 않는다 - 불변성: 정식 릴리스된 Schema 디렉토리의 파일은 릴리스 후 더 이상 수정되지 않는다. 오류 수정을 포함한 모든 Schema 변경은 새 버전 릴리스를 통해 이루어진다
- 이력 보존: 이전 버전의 Schema 디렉토리는 저장소에 영구 보존되며, 역사적 참조 및 하위 호환성 검증에 사용된다
현재 버전 대응 관계:
| 프로토콜 버전 | Schema 디렉토리 | 상태 |
|---|---|---|
| draft | schema/draft/ | 개발 중 |
| 2025-10-25 | schema/2025-10-25/ | 릴리스 완료 |
5.4 Schema 파일 형식 설명
각 Schema 버전 디렉토리에는 3가지 형식의 Schema 정의 파일이 포함되며, 각각 서로 다른 사용 시나리오와 소비자를 대상으로 한다:
| 형식 | 파일명 | 용도 | 주요 소비자 |
|---|---|---|---|
| JSON Schema | schema.json | 기계 가독 메시지 형식 정의로, 자동화 검증, 코드 생성 및 크로스 언어 상호운용성 검증에 사용 | 자동화 도구, CI/CD 파이프라인, SDK 코드 생성기 |
| TypeScript | schema.ts | TypeScript 유형 정의로, TypeScript/JavaScript 생태계에 네이티브 유형 지원을 제공하며, TS/JS SDK 개발 및 IDE 유형 검사에 사용 | TypeScript/JavaScript SDK 개발자, 프론트엔드 통합 개발자 |
| MDX | schema.mdx | 렌더링 가능한 문서 형식으로, Schema 정의를 인간 친화적인 방식으로 제시하며, 문서 사이트 전시 및 프로토콜 학습에 사용 | 프로토콜 학습자, 문서 사이트, 기술 리뷰어 |
세 가지 형식의 관계:
- schema.json이 권위적 형식: 세 가지 형식 간에 차이가 존재할 때, schema.json을 기준으로 한다. schema.ts와 schema.mdx는 schema.json과 의미적 일관성을 유지해야 한다
- schema.ts는 개발 편의 형식: schema.ts는 schema.json의 유형 정의를 TypeScript 네이티브 유형으로 변환하여 TS/JS 개발자가 IDE에서 직접 유형 힌트와 컴파일 시 검사를 받을 수 있게 한다
- schema.mdx는 전시 형식: schema.mdx는 schema.json의 구조화된 정의를 렌더링 가능한 문서 내용으로 변환하여 문서 사이트에서 대화형 방식으로 Schema 정의를 탐색할 수 있도록 지원한다
파일 디렉토리 구조 예시:
schema/
├── draft/
│ ├── schema.json
│ ├── schema.ts
│ └── schema.mdx
└── 2025-10-25/
├── schema.json
├── schema.ts
└── schema.mdx